oro.nifti (version 0.4.3)

Audit Trails: Facilitate the Creation and Modification of Audit Trails

Description

Facilitate the creation and modification of audit trails for NIfTI class objects.

Usage

oro.nifti.info(type)
enableAuditTrail()
newAuditTrail()
niftiExtensionToAuditTrail(nim, workingDirectory = NULL,
                           filename = NULL, call = NULL)
niftiAuditTrailToExtension(nim, workingDirectory = NULL,
                           filename = NULL, call = NULL)
niftiAuditTrailSystemNode(type="system-info",
                          workingDirectory = NULL,
                          filename = NULL, call = NULL)
niftiAuditTrailSystemNodeEvent(trail, type = NULL, call = NULL,
                               workingDirectory = NULL,
                               filename = NULL, comment=NULL)
niftiAuditTrailCreated(history = NULL, call = NULL,
                       workingDirectory = NULL, filename = NULL)
niftiAuditTrailEvent(trail, type = NULL, call = NULL,
                     comment = NULL)
getLastCallWithName(functionName)

Arguments

nim

is an object of class niftiAuditTrail or can be converted to such.

workingDirectory

The working directory associated with the filename.

filename

The filename associated with the nifti object.

call

A call, function name in the call-stack or a string.

type

An identifier to add some meaning to the event.

trail

The XMLAbstractNode representing the audit trail or the niftiAuditTrail object with a trail that will be amended.

comment

Some textual comment

history

An XMLAbstractNode to store historical events for inclusion in the trail.

functionName

The name of a function on the call stack.

Details

The function oro.nifti.info is used to find the ecode or the XML namespace relevant to the audit trail.

The function enableAuditTrail is turned off by default to minimize package dependencies. Should one wish to turn on the audit trail functionality, then one should set the option NIfTI.audit.trail to TRUE and call the function enableAuditTrail. Setting the option NIfTI.audit.trail to FALSE will disable the audit trail.

The function newAuditTrail returns an XMLAbstractNode representing the root node of an audit trail. This is mostly intended as an internal function.

The function niftiExtensionToAuditTrail takes an object representing a NIfTI object, casts it as a niftiAuditTrail and checks if there is an extension (a niftiExtensionSection) with ecode equal to oro.nifti.info("ecode"); i.e. has a extension with data representing a serialized audit trail. The function will then strip the object of this extension parsing the serialized edata into an audit trail and adding a read event to the trail.

The function niftiAuditTrailToExtension takes a niftiAuditTrail and returns a niftiExtensionSection with edata containing the serialized form of the audit trail after adding a saved event to the trail.

The function niftiAuditTrailSystemNodeEvent adds an element with name equal to type to the trail. It uses the niftiAuditTrailSystemNode function to create the node. The function niftiAuditTrailSystemNode is an internal function creating an XMLAbstractNode element with name type and attributes giving information about the R system and library. The filename and call will also be added as attributes if available.

The function niftiAuditTrailEvent adds an element with name event to the trail. The arguments type, filename, call are added as attributes and the comment is the text value of the element.

The function niftiAuditTrailCreated will create a new audit trail containing a system node element created with the child history with the contents history. If the last element of the history given is an event with type="processing", then this node will be removed from the history and its call attribute will be used as the value of the call attribute on the created node.

The function getLastCallWithName will search the call stack for a call of the function functionName, returning last call to that function if possible. It will default to the call of the function which called the function which called getLastCallWithName if there was no such call (and if there was no such call it will return the call of itself).

Examples

## A good example of the use of these functions is shown by this
## wrapper function which takes a function fun(nim, ...) returning
## lists of arrays which are nifti-ized using as(...)
options("niftiAuditTrail"=TRUE)
enableAuditTrail()

wrapper <- function(functionToWrap, nameOfCallingFunction, nim, ...) {
  if (!is(nim, "nifti")) 
    nim <- as(nim, "nifti")
  
  if (is(nim, "niftiAuditTrail")) {
    ## This will force as(...) to set the call which created the
    ## results to the calling function's call rather than
    ## as(result, nifti) as it would otherwise do
    nim@trail <- niftiAuditTrailEvent(nim@trail, "processing",
                                      nameOfCallingFunction)
  }
  
  result <- functionToWrap(nim, ...)
  as(result, "nifti") <- nim
  return(result)
}

## An example of how wrapper is used follows:
functionToWrap <- function(ignored, x, y) {
  return (array(1, dim=c(x,y)))
}

## The niftiized form
niftiizedForm <- function(nim,...) {
  return(wrapper(functionToWrap, "niftiizedForm", nim, ...))
}

## compare the trails
if (isTRUE(getOption("niftiAuditTrail"))) {
  print((as.nifti(functionToWrap(nifti(), 4, 4), nifti()))@trail)
  print(niftiizedForm(nifti(), 4, 4)@trail)
}